home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / Misc / TN.MISC.014 < prev    next >
Encoding:
Text File  |  1989-08-21  |  8.4 KB  |  159 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple II Miscellaneous
  8. #14:    Guidelines for Telecommunication Programs
  9.  
  10. Written by:    Matt Deatherage                                      July 1989
  11.  
  12. This Technical Note discusses recommended guidelines to ensure future 
  13. compatibility and maintain workable standards for telecommunication programs.
  14. _____________________________________________________________________________
  15.  
  16. Telecommunication programs have always been a particularly troublesome area on 
  17. the Apple II as far as standards are concerned.  Exiting from terminal 
  18. programs often leaves the system in an unbalanced state or leaves strange and 
  19. unknown things upon the user's disks.  Yet complying with standards would not 
  20. only make life easier for the users, it's not that hard for developers to do.  
  21. This Note lists the primary guidelines Apple II telecommunication program 
  22. developers should keep foremost in their minds.
  23.  
  24.  
  25. Talking to the Hardware
  26.  
  27. Communicating with the modem through the interface provided by the user isn't 
  28. always the easiest task in the world.  It often just can't be done at 
  29. acceptable speeds when using high-level software routines, and sometimes it 
  30. can't even be done at the firmware level.  It's widely known that the Super 
  31. Serial Card can't keep up with 9600 bps communication unless a low-level 
  32. driver uses the 6551 chip on the card directly--the firmware just can't do it.  
  33. The Apple IIGS serial port firmware can easily keep up with 9600 bps, but the 
  34. GS/OS generated character drivers for those ports can't do single character 
  35. I/O at that speed.
  36.  
  37. In general, programs must use the highest level interface available to them 
  38. that functions to specifications.  If dealing with speeds of less than 9600 
  39. baud in 16-bit mode, on the Apple IIGS, use the GS/OS drivers.  Remember that 
  40. any GS/OS driver owns the slot or port it controls, and going around the 
  41. drivers causes problems.  High-speed, highly-configurable loaded drivers for 
  42. the serial ports may ship with the System Software in the future, and it would 
  43. be unfortunate if your terminal program was the one that caused the driver to 
  44. break.
  45.  
  46. For speeds of 9600 bps or higher with System Software 5.0, the driver can't 
  47. help you.  It is necessary to go directly to the firmware or hardware and risk 
  48. of future incompatibility.  Remember that the firmware must be called from 
  49. bank zero emulation mode.  If single character I/O isn't necessary, the driver 
  50. can handle speeds of 9600 bps when used in multicharacter input or output.
  51.  
  52. Note:  In the future, System Software may include loaded drivers 
  53.        for the serial ports.  An application can tell whether a driver is 
  54.        generated or loaded by examining bit 14 of the characteristics 
  55.        word returned by the GS/OS DInfo call--a generated driver has this 
  56.        bit set.  A loaded driver may be able to handle 9600 bps single-
  57.        character I/O, but a generated one may not.
  58.  
  59.  
  60. File Transfer Considerations
  61.  
  62. Transferring files is probably the most important function of a 
  63. telecommunication program.  However, transferring the file's data itself is 
  64. not always adequate.  Telecommunication programs must find a way to transfer a 
  65. file's attributes as well as a file's contents to keep things running 
  66. smoothly.
  67.  
  68. File attributes include the file's type and auxiliary type (necessary fields 
  69. for most applications to identify their data files), the size of the file, 
  70. creation and modification dates and times, as well as information about how 
  71. many forks the file has, what file system it came from, and how the file is 
  72. stored on disk.  In addition, when asked, GS/OS returns in its option_list 
  73. information about the file that the native file system uses but GS/OS does not 
  74. (information such as access privileges, native file types and creator types, 
  75. parent directory IDs, extended attribute records and other information as 
  76. important to the native file system as file type and auxiliary type are to 
  77. GS/OS).
  78.  
  79. Any telecommunication program can devise a way to keep such attributes with a 
  80. file when the file is transferred between two machines that are both running 
  81. the program in question.  It is a much trickier task to address the issue of 
  82. keeping all file attributes with files regardless of the programs involved 
  83. in the transfer.  An industry-wide standard is necessary for such integration.
  84.  
  85. The Binary II standard, devised by Gary B. Little (and documented in the Apple 
  86. II File Type Note for File Type $E0, Auxiliary Type $8000), has been accepted 
  87. as a standard for maintaining these attributes for a number of years.  Many 
  88. major telecommunication programs already incorporate support for this 
  89. standard; Apple urges those that don't to consider doing so at their earliest 
  90. convenience.
  91.  
  92. Binary II is designed to keep attributes with files on the fly--it is not an 
  93. archival standard and should not be used as such.  A standard like Binary II 
  94. should always be used to keep attributes with a file; confusing it with an 
  95. archival standard can result in files being transferred without their own 
  96. attributes.  Even archival files must be transferred with their attributes.  
  97. It is never acceptable to transfer a file without it's attributes.
  98.  
  99. Archival considerations are a completely separate issue.  An archival format 
  100. and program must be carefully designed with archiving considerations in mind, 
  101. such as manipulating files within the archive, preserving the attributes of 
  102. the files archived, and allowing for a myriad of compression schemes.  The 
  103. NuFX standard (documented in the Apple II File Type Note for File Type $E0, 
  104. Auxiliary Type $8002) is such an archival format, which Apple recommends be 
  105. used for those purposes.  The program ShrinkIt is an example of a NuFX 
  106. archival utility.
  107.  
  108. In an ideal world, all files would be transferred with their attributes sent 
  109. transparently by the telecommunication program.  The user would select the 
  110. file to send, and the program would automatically send the attributes.  When 
  111. the program receives a file, it would already have the attributes with the 
  112. file, so no postprocessing by the user would be necessary to use the file.
  113.  
  114. Even archival files such as NuFX should be transferred with all attributes 
  115. intact.  Although the archival utility may allow the user to select any file 
  116. for processing (in case the file's attributes were lost), assuming that this 
  117. will happen implies that it's acceptable.  It is not.  No file should ever be 
  118. transferred without all its attributes, down to, and including the  GS/OS 
  119. option_list, if present.
  120.  
  121.  
  122. Apple IIGS Considerations
  123.  
  124. A few more guidelines for Apple IIGS-specific telecommunication applications 
  125. follow:
  126.  
  127.   o  Don't ignore slot configurations.  Attempting to use a 
  128.      serial port through hardware while an interface card for that slot 
  129.      is switched in will break dynamic slot arbitration if, and when, 
  130.      it becomes available, unless the application does not use the 
  131.      firmware.
  132.  
  133.   o  Be a good neighbor to interrupt handlers.  Interrupts will 
  134.      be coming through that you did not enable.  (This is also true for 
  135.      Apple IIe computers with Workstation Cards, but is true for IIGS 
  136.      computers even when AppleTalk is not involved.)  Programs not 
  137.      prepared for this could bring the system down.  Stealing main 
  138.      interrupt vectors is not a good idea.
  139.  
  140.   o  Don't go stepping on things you don't own.  It is better 
  141.      to alert the user that a certain resource (like a slot or a port) 
  142.      is not available than to blindly switch it in and crash the 
  143.      system.  Never switch slots without using the Slot Arbiter.
  144.  
  145.   o  Behave yourself.  Don't make wild assumptions or do things 
  146.      differently just because you're a terminal program and you think 
  147.      you have to do it for speed.  Most users won't be impressed by a 
  148.      terminal program that's fast and robust if it breaks every time 
  149.      they activate a desk accessory or if they have to reboot the 
  150.      system when they're done with it.  Don't compromise system 
  151.      integrity for superficial functionality.
  152.  
  153.  
  154. Further Reference
  155. _____________________________________________________________________________
  156.     o    Apple IIGS Firmware Reference
  157.     o    Apple IIGS Hardware Reference
  158.     o    Apple II File Type Notes, File Type $E0, Auxiliary Type $8000
  159.     o    Apple II File Type Notes, File Type $E0, Auxiliary Type $8002